%TODO: This might easily be transformed into API Docs
%TODO: More message passing functions?
%TODO: more system calls for the superviser stuff
%TODO: What happens if the superviser dies before it's supervised processes die?  Maybe an unregister syscall? @Bogdan: This is sth. you should think about

%Remark: This might change drastically during the actual
% development. There are some points that need to be discussed.

\chapter{PORN-OS Application Programming Interface (PORN-OS API)}

\section{Introduction}

To simplify the development of user applications and to abstract hardware specific operations and complexity away from these, PORN-OS comes with a custom API.

The API is made available to the application programmer as a set of C-functions.
The System Call functions have french names to express the OS's distinctness from existing Unices or other existing operating systems.
The API will be seen by the user program as a set of .h files, which will reside in the /include/api folder of the project source code.

If the application program wants to issue a system call, it needs to store the number of the desired system call into the \texttt{v0}-register and the parameters of the system call into other registers depending on the actual system call.
After that the user level (UL) program executes the SYSCALL command on thus creates an exception on the MIPS-processor. 
The cause register is set to 8 (syscall). The Exception handler (which is part of our Operating System) will figure out which system call is to be executed from the \texttt{v0}-register and will execute the desired operations, by calling its internal low level functions. 
%During this time the application program is out of the ready queue. 
When the execution of the system call is finished. Control flow goes back to the calling application program, if this is in agreement with the scheduling policies. 

To give an example, the UL side of the system call \texttt{ecrire} might look like this:
\begin{lstlisting}
                .data
string1	       .asciiz	"Print this.\n" # declaration for string variable
                .text
ecrire:         li $v0, ECRIRE          # load system call code into reg. $v0;
                                        # this code can be found in syscall.h
                la $a0, string1         # load address of str into $a0
                syscall                 # call OS to perform print operation 
\end{lstlisting}
All system calls will load a system call code into \texttt{v0} and execute syscall. The parameters are specific to the system call.

\pagebreak
\section{System Call Overview}

We identified the following system calls in our OS. The set of system calls tha are actually going to be implemented, might change during implementation.
The system calls are grouped by similarity in the following table

\vspace{2cm}
\begin{tabular}{llp{7cm}}
Name & pseduo-unixoid-equivalent & short description \\ \hline

fourchette & fork & create another process executing a given program \\
%executer & exec & replace the current process image with another process \\
tuer & kill & stop the execution of another process, this is distinct from UNIX, because there will be no signals in the system \\
quitter & exit & inform PORN-OS that the execution of the calling process is finished and hand control flow back to the OS \\ \hline

obtenir\_programme & get\_progname & the calling process gets its own name \\ 
obtenir\_pid & get\_pid & the calling process gets its own pid. \\
obtenir\_priorite & get\_priority & get the priority of a process via its pid \\
obtenir\_tous\_pids & get\_al\_pids & get a list of all pids that are currently in use \\ \hline

ecrire & printf & print a string to tty0 \\
ecrire\_LCD & printf\_LCD & print a (short) string to malta0 \\
obtenir\_temps & get\_time & get the current system time, this might split up to several syscalls \\
lire & scanf & read a string from tty0 (user input)\\ \hline

bloquer & block &  take the calling process out of the schedulers ready queue \\
reveiller & wake & wake up a process that has been blocked before \\
retarder & delay &  delay the execution of the calling process for a specified amount of time \\ \hline


allouer & malloc & dynamical memory allocation; return a pointer to memory that can be used by the calling process \\
liberer & free & inform the OS that a certain amount of memory is no longer used by the calling process \\ \hline


%envoyer\_message & send\_message & send a char string to another process \\
envoyer\_chaine & send\_string & send a char string to another process \\
envoyer\_entier & send\_int & send an integer to another process \\
recevoir\_message & receive\_message & receive a message from another process, this might block the caller. \\ \hline


enregistrer\_superviseur & register\_supervisor & register a process as a supervisor to other processes \\
changer\_priorite & change\_priority &  changes a processes priority and invokes the scheduler \\

\end{tabular}

\pagebreak
The system calls are assigned a unique number, so that the operating system can tell them apart after SYSCALL has been issued:
These definitions should be stored in /include/api/syscall.h

\lstinputlisting[frame=single]{files/syscall.h}


\section{More in detail description  of the single system calls}

The following contains are more detailed description of the single sysem calls that are to be implemented. 

There is a general convention on return codes:
\begin{lstlisting}
#define EXIT_SUCCESS 0
#define EXIT_FAILURE 1
\end{lstlisting}

\subsection{\texttt{int fourchette(char* progname)}}

\begin{description}
\item[OUT] return value
\end{description}

It creates a new process by allocating a PCB to it. The program this new process executes is given by the parameter \emph{progname}.
It returns the PID of the created process to the sender. Since the program executed by the newly created process may be different, it does not return anything to the created process. 

%\subsection{\texttt{int executer(char* progname)}}

%\begin{description}
%\item[IN] progname: name of the program to be executed in the calling process
%\item[OUT] return value
%\end{description}

%The PCB of a process gets altered so that the program \emph{progname}
%gets executed. This has influence on the PC and some other values in
%the PCB.  There might be a derivative of this function, that spawns
%processes, but takes the number of a program from the progam table as
%input.

%The return code follows the convention stated above.

\subsection{\texttt{void tuer(int procId)}}

\begin{description}
\item[IN] procId: process id of the process to be terminated
\end{description}

The process with the id procId gets terminated and its PCB gets
deleted. All the resources that this process occupied get reclaimed by
the system. This should in particular also be useful if a process
wants to exit, so it can just kill itself.

A return code here would not make sense. If this function call fails,
it has to be handled in the kernel.
	
\subsection{\texttt{void quitter() }}

The caller gets terminated. We can easily implement this as
\begin{lstlisting}
void quitter(){ 
    tuer(obtenir\_pid()); 
}
\end{lstlisting}
         
A return code here would not make sense. If this function call
fails, it has to be handled in the kernel.

Addendum: We might add return codes in a later version, but I
guess that we don't need them in our little project.

\subsection{\texttt{int obtenir\_programme(char* progname, int  pid) }}

\begin{description}
\item[OUT] progname: buffer in which the received program name is written to
\item[IN] pid: pid of the process, whose name we want to know
\item[OUT] return value
\end{description}

A program receives the program name of \emph{pid}. This is a textual
representation of what the program does, e.g. 'Fibonnaci'. The program
name has to be of fixed size, so that the user knows how much memory
has to be reserved for nameBuffer.

The return code follows the convention stated above.

\subsection{\texttt{int obtenir\_pid(int* myPid) }}

\begin{description}
\item[OUT] myPid: the calling process receives it's pid at the address myPid
\item[OUT] return value
\end{description}
         
Returns the processes' pid. This should be easy to implement. The int
value from the PCB just needs to be copied to a register.

The return code follows the convention stated above.

\subsection{\texttt{int obtenir\_priorite(int* newPriority, int pid) }}

\begin{description}
\item[IN] pid: process id of the process, whose priority we wish to manipulate
\item[IN] newPriority: priority we wish to assign to this process
\item[OUT] return value
\end{description}

Similar to \texttt{int obtenir\_pid() }, but instead of the pid, the
proc priority gets copied.

\emph{priority} is a pointer to an int, where the priority should be
stored.

The return code follows the convention stated above.

\subsection{\texttt{int obtenir\_tous\_pid(int* pidList) }}

\begin{description}
\item[OUT] pidList: an array containg all currently existing pids
\item[OUT] return value
\end{description}

Return an array with the pids of all processes that currently exist in
the system. The array needs to have a size of MAX\_NUM\_PROCS to be on
the safe side. The array contains the value INVALID\_PID (we could
define this as 0) in some entries, if the amount of processes in the
system is smaller than MAX\_NUM\_PROCS.

The return code follows the convention stated above.

\subsection{\texttt{int ecrire(char* string)}}

\begin{description}
\item[OUT] string: the string that is supposed to be written to tty0
\item[OUT] return value
\end{description}

Write to tty0.  Executes a system call, write strin to certain text
buffer. Here we need to solve the readers/writers problem from the
lecture to make sure there are no interleavings in the output of
different processes.  the console/scroller handles the buffer and
takes care of the actual writing to the screen at some point.  the
system waits until tty0 is available, ie it is not blocked by any
other process and performs the write operation.

There might be derivatives of this function to print integers, etc.

The return code follows the convention stated above.

\subsection{\texttt{int ecrire\_LCD(char* string)}}

\begin{description}
\item[OUT] string: the string that is supposed to be written to malta0
\item[OUT] return value
\end{description}

Write to malta0. Similar to ecrire, but more simplistic because the
display has only 8 digits.  The console/scroller part should be very
simple compared to the console for ecrire.

If the input is too long, only the first 8 characters gets printed.

The return code follows the convention stated above.

\subsection{\texttt{int obtenir\_temps(int* time)}}

\begin{description}
\item[OUT] time: the time is written to this pointer
\item[OUT] return value
\end{description}

Return the present system time, probably milli/microseconds This might
get split up into several other system calls, e.g to get the time in
seconds/min/hours Besides there needs to be a system call that gets a
pointer to a function and a certain amount of time. If this amount of
time has expired, the function that was handed over via the function
pointer gets called. This function would be used to implent wake/delay
events etc.

The return code follows the convention stated above.

\subsection{\texttt{int lire(char* textInput, length)}}

\begin{description}
\item[OUT] textInput: the input that was read from tty0 is written to this pointer
\item[IN] length: amount of chars we want to read 
\item[OUT] return value
\end{description}

Reads a string from tty0. In the beginning we can implement a simplified version, in which buffer can be of fixed length. We also pass \emph{length} to the function, so the function knows how many characters it should read at most.

The return code follows the convention stated above.	

\subsection{\texttt{int bloquer()}}

\begin{description}
\item[OUT] return value
\end{description}

Blocks a process. The process is taken out of the ready queue and its execution is stopped. The process can continue execution if it gets woken up by another process (ref. \emph{reveiller}).

The return code follows the convention stated above.	

\subsection{\texttt{int reveiller(int pId)}}

\begin{description}
\item[IN] pId: process id of the process that should be wake up
\item[OUT] return value
\end{description}

Wakes the process with process id = pId. The process gets into the
\emph{Ready Queue} and eventually gets to execute if its priority
allows it.

The return code follows the convention stated above.	

\subsection{\texttt{int retarder(int delayTime, pId)}}

\begin{description}
\item[IN] delayTime: time (might be msec) for which we want to delay a process
\item[IN] pId: process id of the process we want to delay
\item[OUT] return value
\end{description}

Delay a process for a certain amount of time, eg delayTime
milliseconds.

The return code follows the convention stated above.	

\subsection{\texttt{(void)* allouer(int sizeInBytes)}}

\begin{description}
\item[IN] sizeInBytes: the amount of bytes we want to allocate
\end{description}

Returns a pointer to a memory location that is sizeInBytes big. If
the pointer is NULL the memory allocation has failed. How the
memory allocation works is described in this specific section of
the manual.

\subsection{\texttt{int liberer((void)* memLocation) }}

\begin{description}
\item[IN] memLocation: pointer to the variable/structure that should be freed
\item[OUT] return value
\end{description}

Tell the OS that the memory block that starts at memLocation
is no longer required by the calling process. The OS needs to
keep track how big this section is. We will probably have a
table that lists all processes and how many memory segments
they have, at which locations they start and how big they are.

The return code follows the convention stated above.	

\subsection{\texttt{int envoyer\_message(char* message, int recPid, int messageTag) }}

\begin{description}
\item[IN] message: the message that is to be sent
\item[IN] recPid: the process id of the receiving process
\item[IN] messagePriority: priority of the message
\item[OUT] return value
\end{description}

This function constructs a new message using the parameters and copies it to the next
free location in the message buffer of the respective process. This function will have derivates, that can be used to send messages of different types, e.g an integer. The interpretation of the received string will be up to the receiver. The \emph{messagePriority} can be used to used to differentiate between different messages in the message buffer, esp. from the same sender. 

The return code follows the convention stated above.	
The return code is different from 0 if sending the message failed (eg
message buffer full)

%I think we don't need a priority, etc. beyond this

\subsection{\texttt{int recevoir\_message(message* message, int senderPid, int messagePriority)}}

\begin{description}
\item [OUT] message: the received message will be stored here
\item [IN] messagePriority: the message priority, may be used as a tag to identify a message
\item [IN] senderPid: process id of the sender, this is a way to select messages from the queue
\item [OUT] return value
\end{description}

Check the message buffer for messages of the desired tag and
sender. This might involve calling bloquer(). 

It will be possible to set the filters parameters to a given value that disable it. 

The return code follows the convention stated above.

\subsection{\texttt{int enregistrer\_superviseur(int supervisorProcId) }}

Register the process with supervisorProcId as supervisor. This
processes PCB needs to be modified so that it represents a supervisor
PCB.  The return code tells if the operation succeeded.  

The supervising capabilities of PORN-OS will require more API
functions that have not yet all been discovered. Check out the supervision part to find more information.
  
The return code follows the convention stated above.	
 

\subsection{\texttt{int changer\_priorite(int procId, int priority) }}

\begin{description}
\item [IN] procId: a arbitrary tag that identifies a message (similar to MPI)
\item [IN] priority: process id of the sender, this is a way to select messages from the queue
\item [OUT] return value
\end{description}

Change the priority value in the PCB of the process with id = procId to priority.
There is no security model, so any process can change any other processes' priority.
The return code tells if the operation succeeded.

The return code follows the convention stated above.	
